home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / CrtPipelin.3 < prev    next >
Text File  |  1993-01-31  |  5KB  |  106 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/CrtPipelin.3,v 1.3 93/01/31 15:35:31 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .so man.macros
  13. .HS Tcl_CreatePipeline tcl
  14. .VS
  15. .BS
  16. .SH NAME
  17. Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
  18. .SH SYNOPSIS
  19. .nf
  20. \fB#include <tcl.h>\fR
  21. .sp
  22. int
  23. \fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
  24. .SH ARGUMENTS
  25. .AS Tcl_Interp **pidArrayPtr
  26. .AP Tcl_Interp *interp in
  27. Interpreter to use for error reporting.
  28. .AP int argc in
  29. Number of strings in \fIargv\fR array.
  30. .AP char **argv in
  31. Array of strings describing command(s) and I/O redirection.
  32. .AP int **pidArrayPtr out
  33. The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
  34. an array of process identifiers.  The array is dynamically
  35. allocated and must be freed by the caller.
  36. .AP char *inPipePtr out
  37. If this argument is NULL then standard input for the first command
  38. in the pipeline comes from the current standard input.
  39. If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  40. create a pipe, arrange for it to be used for standard input
  41. to the first command,
  42. and store a file id for writing to that pipe at \fI*inPipePtr\fR.
  43. If the command specified its own input using redirection, then
  44. no pipe is created and -1 is stored at \fI*inPipePtr\fR.
  45. .AP char *outPipePtr out
  46. If this argument is NULL then standard output for the last command
  47. in the pipeline goes to the current standard output.
  48. If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  49. create a pipe, arrange for it to be used for standard output from
  50. the last command, and store a file id for reading from that
  51. pipe at \fI*outPipePtr\fR.
  52. If the command specified its own output using redirection then
  53. no pipe is created and -1 is stored at \fI*outPipePtr\fR.
  54. .AP char *errFilePtr out
  55. If this argument is NULL then error output for all the commands
  56. in the pipeline will go to the current standard error file.
  57. If \fIerrFilePtr\fR is not NULL, error output from all the commands
  58. in the pipeline will go to a temporary file created by
  59. \fBTcl_CreatePipeline\fR.
  60. A file id to read from that file will be stored at \fI*errFilePtr\fR.
  61. The file will already have been removed, so closing the file
  62. descriptor at \fI*errFilePtr\fR will cause the file to be flushed
  63. completely.
  64. .BE
  65.  
  66. .SH DESCRIPTION
  67. .PP
  68. \fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
  69. up one or more child processes in a pipeline configuration.
  70. \fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
  71. input redirection specified with ``<'' or ``<<'', and output
  72. redirection specified with ``>'';  see the documentation for
  73. the \fBexec\fR command for details on these specifications.
  74. The return value from \fBTcl_CreatePipeline\fR is a count of
  75. the number of child processes created;  the process identifiers
  76. for those processes are stored in a \fImalloc\fR-ed array and
  77. a pointer to that array is stored at \fI*pidArrayPtr\fR.
  78. It is the caller's responsibility to free the array when finished
  79. with it.
  80. .PP
  81. If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
  82. arguments are NULL then the pipeline's standard input, standard
  83. output, and standard error are taken from the corresponding
  84. streams of the process.  Non-NULL values may be specified for
  85. these arguments to use pipes for standard input and standard
  86. output and a file for standard error.  \fBTcl_CreatePipeline\fR
  87. will create the requested pipes or file and return file identifiers
  88. that may be used to read or write them.  It is the caller's
  89. responsibility to close all of these files when they are no
  90. longer needed.  If \fIargv\fR specifies redirection for standard
  91. input or standard output, then pipes will not be created even
  92. if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
  93. arguments.
  94. .PP
  95. If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
  96. ``<'' was the last argument in \fIargv\fR, or it wasn't possible
  97. to fork off a child), then -1 is returned
  98. and \fIinterp->result\fR is set to an error message.
  99.  
  100. .SH "SEE ALSO"
  101. \fBTcl_WaitPids\fR, \fBTcl_DetachPids\fR
  102.  
  103. .SH KEYWORDS
  104. background, child, detach, fork, process, status, wait
  105. .VE
  106.